home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / sources / misc / volume24 / gnucalc / part51 < prev    next >
Encoding:
Text File  |  1991-11-02  |  55.5 KB  |  1,401 lines

  1. Newsgroups: comp.sources.misc
  2. From: daveg@synaptics.com (David Gillespie)
  3. Subject:  v24i099:  gnucalc - GNU Emacs Calculator, v2.00, Part51/56
  4. Message-ID: <1991Nov3.001052.19800@sparky.imd.sterling.com>
  5. X-Md4-Signature: f137f14d9adc4e0fd7629cf3d509f3b6
  6. Date: Sun, 3 Nov 1991 00:10:52 GMT
  7. Approved: kent@sparky.imd.sterling.com
  8.  
  9. Submitted-by: daveg@synaptics.com (David Gillespie)
  10. Posting-number: Volume 24, Issue 99
  11. Archive-name: gnucalc/part51
  12. Environment: Emacs
  13. Supersedes: gmcalc: Volume 13, Issue 27-45
  14.  
  15. #!/bin/sh
  16. # do not concatenate these parts, unpack them in order with /bin/sh
  17. # file calc.texinfo continued
  18. #
  19. if test ! -r _shar_seq_.tmp; then
  20.     echo 'Please unpack part 1 first!'
  21.     exit 1
  22. fi
  23. (read Scheck
  24.  if test "$Scheck" != 51; then
  25.     echo Please unpack part "$Scheck" next!
  26.     exit 1
  27.  else
  28.     exit 0
  29.  fi
  30. ) < _shar_seq_.tmp || exit 1
  31. if test ! -f _shar_wnt_.tmp; then
  32.     echo 'x - still skipping calc.texinfo'
  33. else
  34. echo 'x - continuing file calc.texinfo'
  35. sed 's/^X//' << 'SHAR_EOF' >> 'calc.texinfo' &&
  36. stay the same; the top three rows change to a new set of commands.
  37. To return to earlier menus, click the middle mouse button
  38. [@code{calc-keypad-menu-back}] or simply advance through the menus
  39. until you wrap around.  Typing @key{TAB} inside the keypad window
  40. is equivalent to clicking the right mouse button there.
  41. X
  42. You can always click the @key{EXEC} button and type any normal
  43. Calc key sequence.  This is equivalent to switching into the
  44. Calc buffer, typing the keys, then switching back to your
  45. original buffer.
  46. X
  47. @menu
  48. * Keypad Main Menu::
  49. * Keypad Functions Menu::
  50. * Keypad Binary Menu::
  51. * Keypad Vectors Menu::
  52. * Keypad Modes Menu::
  53. @end menu
  54. X
  55. @node Keypad Main Menu, Keypad Functions Menu, Keypad Mode, Keypad Mode
  56. @section Main Menu
  57. X
  58. @group
  59. @smallexample
  60. |----+-----Calc 2.00-----+----1
  61. |FLR |CEIL|RND |TRNC|CLN2|FLT |
  62. |----+----+----+----+----+----|
  63. | LN |EXP |    |ABS |IDIV|MOD |
  64. |----+----+----+----+----+----|
  65. |SIN |COS |TAN |SQRT|y^x |1/x |
  66. |----+----+----+----+----+----|
  67. |  ENTER  |+/- |EEX |UNDO| <- |
  68. |-----+---+-+--+--+-+---++----|
  69. | INV |  7  |  8  |  9  |  /  |
  70. |-----+-----+-----+-----+-----|
  71. | HYP |  4  |  5  |  6  |  *  |
  72. |-----+-----+-----+-----+-----|
  73. |EXEC |  1  |  2  |  3  |  -  |
  74. |-----+-----+-----+-----+-----|
  75. | OFF |  0  |  .  | PI  |  +  |
  76. |-----+-----+-----+-----+-----+
  77. @end smallexample
  78. @end group
  79. X
  80. @noindent
  81. This is the menu that appears the first time you start Keypad Mode.
  82. It will show up in a vertical window on the right side of your screen.
  83. Above this menu is the traditional Calc stack display.  On a 24-line
  84. screen you will be able to see the top three stack entries.
  85. X
  86. The ten digit keys, decimal point, and @key{EEX} key are used for
  87. entering numbers in the obvious way.  @key{EEX} begins entry of an
  88. exponent in scientific notation.  Just as with regular Calc, the
  89. number is pushed onto the stack as soon as you press @key{ENTER}
  90. or any other function key.
  91. X
  92. The @key{+/-} key corresponds to normal Calc's @kbd{n} key.  During
  93. numeric entry it changes the sign of the number or of the exponent.
  94. At other times it changes the sign of the number on the top of the
  95. stack.
  96. X
  97. The @key{INV} and @key{HYP} keys modify other keys.  As well as
  98. having the effects described elsewhere in this manual, Keypad Mode
  99. defines several other ``inverse'' operations.  These are described
  100. below and in the following sections.
  101. X
  102. The @key{ENTER} key finishes the current numeric entry, or otherwise
  103. duplicates the top entry on the stack.
  104. X
  105. The @key{UNDO} key undoes the most recent Calc operation.
  106. @kbd{INV UNDO} is the ``redo'' command, and @kbd{HYP UNDO} is
  107. ``last arguments'' (@kbd{M-RET}).
  108. X
  109. The @key{<-} key acts as a ``backspace'' during numeric entry.
  110. At other times it removes the top stack entry.  @kbd{INV <-}
  111. clears the entire stack.  @kbd{HYP <-} takes an integer from
  112. the stack, then removes that many additional stack elements.
  113. X
  114. The @key{EXEC} key prompts you to enter any keystroke sequence
  115. that would normally work in Calc mode.  This can include a
  116. numeric prefix if you wish.  It is also possible simply to
  117. switch into the Calc window and type commands in it; there is
  118. nothing ``magic'' about this window when Keypad Mode is active.
  119. X
  120. The other keys in this display perform their obvious calculator
  121. functions.  @key{CLN2} rounds the top-of-stack by temporarily
  122. reducing the precision by 2 digits.  @key{FLT} converts an
  123. integer or fraction on the top of the stack to floating-point.
  124. X
  125. The @key{INV} and @key{HYP} keys combined with several of these keys
  126. give you access to some common functions even if the appropriate menu
  127. is not displayed.  Obviously you don't need to learn these keys
  128. unless you find yourself wasting time switching among the menus.
  129. X
  130. @table @kbd
  131. @item INV +/-
  132. is the same as @key{1/x}.
  133. @item INV +
  134. is the same as @key{SQRT}.
  135. @item INV -
  136. is the same as @key{CONJ}.
  137. @item INV *
  138. is the same as @key{y^x}.
  139. @item INV /
  140. is the same as @key{INV y^x} (the @cite{x}th root of @cite{y}).
  141. @item HYP/INV 1
  142. are the same as @key{SIN} / @kbd{INV SIN}.
  143. @item HYP/INV 2
  144. are the same as @key{COS} / @kbd{INV COS}.
  145. @item HYP/INV 3
  146. are the same as @key{TAN} / @kbd{INV TAN}.
  147. @item INV/HYP 4
  148. are the same as @key{LN} / @kbd{HYP LN}.
  149. @item INV/HYP 5
  150. are the same as @key{EXP} / @kbd{HYP EXP}.
  151. @item INV 6
  152. is the same as @key{ABS}.
  153. @item INV 7
  154. is the same as @key{RND} (@code{calc-round}).
  155. @item INV 8
  156. is the same as @key{CLN2}.
  157. @item INV 9
  158. is the same as @key{FLT} (@code{calc-float}).
  159. @item INV 0
  160. is the same as @key{IMAG}.
  161. @item INV .
  162. is the same as @key{PREC}.
  163. @item INV ENTER
  164. is the same as @key{SWAP}.
  165. @item HYP ENTER
  166. is the same as @key{RLL3}.
  167. @item INV HYP ENTER
  168. is the same as @key{OVER}.
  169. @item HYP +/-
  170. packs the top two stack entries as an error form.
  171. @item HYP EEX
  172. packs the top two stack entries as a modulo form.
  173. @item INV EEX
  174. creates an interval form; this removes an integer which is one
  175. of 0 @samp{[]}, 1 @samp{[)}, 2 @samp{(]} or 3 @samp{()}, followed
  176. by the two limits of the interval.
  177. @end table
  178. X
  179. The @kbd{OFF} key turns Calc off; typing @kbd{M-# k} or @kbd{M-# M-#}
  180. again has the same effect.  This is analogous to typing @kbd{q} or
  181. hitting @kbd{M-# c} again in the normal calculator.  If Calc is
  182. running standalone (the @code{calc-keypad} command appeared in the
  183. command line that started Emacs), then @kbd{OFF} is replaced with
  184. @kbd{EXIT}; clicking on this actually exits Emacs itself.
  185. X
  186. @node Keypad Functions Menu, Keypad Binary Menu, Keypad Main Menu, Keypad Mode
  187. @section Functions Menu
  188. X
  189. @group
  190. @smallexample
  191. |----+----+----+----+----+----2
  192. |IGAM|BETA|IBET|ERF |BESJ|BESY|
  193. |----+----+----+----+----+----|
  194. |IMAG|CONJ| RE |ATN2|RAND|RAGN|
  195. |----+----+----+----+----+----|
  196. |GCD |FACT|DFCT|BNOM|PERM|NXTP|
  197. |----+----+----+----+----+----|
  198. @end smallexample
  199. @end group
  200. X
  201. @noindent
  202. This menu provides various operations from the @kbd{f} and @kbd{k}
  203. prefix keys.
  204. X
  205. @key{IMAG} multiplies the number on the stack by the imaginary
  206. number @cite{i = (0, 1)}.
  207. X
  208. @key{RE} extracts the real part a complex number.  @kbd{INV RE}
  209. extracts the imaginary part.
  210. X
  211. @key{RAND} takes a number from the top of the stack and computes
  212. a random number greater than or equal to zero but less than that
  213. number.  (@xref{Random Numbers}.)  @key{RAGN} is the ``random
  214. again'' command; it computes another random number using the
  215. same limit as last time.
  216. X
  217. @key{INV GCD} computes the LCM (least common multiple) function.
  218. X
  219. @key{INV FACT} is the gamma function.  @c{$\Gamma(x) = (x-1)!$}
  220. @cite{gamma(x) = (x-1)!}.
  221. X
  222. @key{PERM} is the number-of-permutations function, which is on the
  223. @kbd{H k c} key in normal Calc.
  224. X
  225. @key{NXTP} finds the next prime after a number.  @kbd{INV NXTP}
  226. finds the previous prime.
  227. X
  228. @node Keypad Binary Menu, Keypad Vectors Menu, Keypad Functions Menu, Keypad Mode
  229. @section Binary Menu
  230. X
  231. @group
  232. @smallexample
  233. |----+----+----+----+----+----3
  234. |AND | OR |XOR |NOT |LSH |RSH |
  235. |----+----+----+----+----+----|
  236. |DEC |HEX |OCT |BIN |WSIZ|ARSH|
  237. |----+----+----+----+----+----|
  238. | A  | B  | C  | D  | E  | F  |
  239. |----+----+----+----+----+----|
  240. @end smallexample
  241. @end group
  242. X
  243. @noindent
  244. The keys in this menu perform operations on binary integers.
  245. Note that both logical and arithmetic right-shifts are provided.
  246. @key{INV LSH} rotates one bit to the left.
  247. X
  248. The ``difference'' function (normally on @kbd{b d}) is on @key{INV AND}.
  249. The ``clip'' function (normally on @kbd{b c}) is on @key{INV NOT}.
  250. X
  251. The @key{DEC}, @key{HEX}, @key{OCT}, and @key{BIN} keys select the
  252. current radix for display and entry of numbers:  Decimal, hexadecimal,
  253. octal, or binary.  The six letter keys @key{A} through @key{F} are used
  254. for entering hexadecimal numbers.
  255. X
  256. The @key{WSIZ} key sets the current word size for binary operations.
  257. The default is 32 bits.  You can respond to the prompt using either
  258. the keyboard or the digits and @key{ENTER} from the keypad.  Use
  259. @key{INV WSIZ} to see the current word size.
  260. X
  261. @node Keypad Vectors Menu, Keypad Modes Menu, Keypad Binary Menu, Keypad Mode
  262. @section Vectors Menu
  263. X
  264. @group
  265. @smallexample
  266. |----+----+----+----+----+----4
  267. |SUM |PROD|MAX |MAP*|MAP^|MAP$|
  268. |----+----+----+----+----+----|
  269. |MINV|MDET|MTRN|IDNT|CRSS|"x" |
  270. |----+----+----+----+----+----|
  271. |PACK|UNPK|INDX|BLD |LEN |... |
  272. |----+----+----+----+----+----|
  273. @end smallexample
  274. @end group
  275. X
  276. @noindent
  277. The keys in this menu operate on vectors and matrices.
  278. X
  279. @key{PACK} removes an integer @var{n} from the top of the stack;
  280. the next @var{n} stack elements are removed and packed into a vector,
  281. which is replaced onto the stack.  Thus the sequence
  282. @kbd{1 ENTER 3 ENTER 5 ENTER 3 PACK} enters the vector
  283. @samp{[1, 3, 5]} onto the stack.  To enter a matrix, build each row
  284. on the stack as a vector, then use a final @key{PACK} to collect the
  285. rows into a matrix.
  286. X
  287. @key{UNPK} unpacks the vector on the stack, pushing each of its
  288. components separately.
  289. X
  290. @key{INDX} removes an integer @var{n}, then builds a vector of
  291. integers from 1 to @var{n}.  @kbd{INV INDX} takes three numbers
  292. from the stack:  The vector size @var{n}, the starting number,
  293. and the increment.  @kbd{BLD} takes an integer @var{n} and any
  294. value @var{x} and builds a vector of @var{n} copies of @var{x}.
  295. X
  296. @key{IDNT} removes an integer @var{n}, then builds an @var{n}-by-@var{n}
  297. identity matrix.
  298. X
  299. @key{LEN} replaces a vector by its length, an integer.
  300. X
  301. @key{...} turns on or off ``abbreviated'' display mode for large vectors.
  302. X
  303. @key{MINV}, @key{MDET}, @key{MTRN}, and @key{CROSS} are the matrix
  304. inverse, determinant, and transpose, and vector cross product.
  305. X
  306. @key{SUM} replaces a vector by the sum of its elements.  It is
  307. equivalent to @kbd{u +} in normal Calc (@pxref{Statistical Operations}).
  308. @key{PROD} computes the product of the elements of a vector, and
  309. @key{MAX} computes the maximum of all the elements of a vector.
  310. X
  311. @key{INV SUM} computes the alternating sum of the first element
  312. minus the second, plus the third, minus the fourth, and so on.
  313. @key{INV MAX} computes the minimum of the vector elements.
  314. X
  315. @key{HYP SUM} computes the mean of the vector elements.
  316. @key{HYP PROD} computes the sample standard deviation.
  317. X
  318. @key{MAP*} multiplies two vectors elementwise.  It is equivalent
  319. to the @kbd{V M *} command (in map-by-elements mode; @pxref{Reducing
  320. and Mapping}).  @key{MAP^} computes powers elementwise.  The arguments
  321. must be vectors of equal length, or one must be a vector and the
  322. other must be a plain number.  For example, @kbd{2 MAP^} squares all
  323. the elements of a vector.
  324. X
  325. @key{MAP$} maps the formula on the top of the stack across the
  326. vector in the second-to-top position.  If the formula contains
  327. several variables, Calc takes that many vectors starting at the
  328. second-to-top position and matches them to the variables in
  329. alphabetical order.  The result is a vector of the same size as
  330. the input vectors, whose elements are the formula evaluated with
  331. the variables set to the various sets of numbers in those vectors.
  332. For example, you could simulate @key{MAP^} using @key{MAP$} with
  333. the formula @cite{x^y}.
  334. X
  335. The @kbd{"x"} key pushes the variable name @cite{x} onto the
  336. stack.  To build the formula @cite{x^2 + 6}, you would use the
  337. key sequence @kbd{"x" 2 y^x 6 +}.  This formula would then be
  338. suitable for use with the @key{MAP$} key described above.
  339. With @key{INV}, @key{HYP}, or @key{INV} and @key{HYP}, the
  340. @kbd{"x"} key pushes the variable names @cite{y}, @cite{z}, and
  341. @cite{t}, respectively.
  342. X
  343. @node Keypad Modes Menu, , Keypad Vectors Menu, Keypad Mode
  344. @section Modes Menu
  345. X
  346. @group
  347. @smallexample
  348. |----+----+----+----+----+----5
  349. |FLT |FIX |SCI |ENG |GRP |    |
  350. |----+----+----+----+----+----|
  351. |RAD |DEG |FRAC|POLR|SYMB|PREC|
  352. |----+----+----+----+----+----|
  353. |SWAP|RLL3|RLL4|OVER|STO |RCL |
  354. |----+----+----+----+----+----|
  355. @end smallexample
  356. @end group
  357. X
  358. @noindent
  359. The keys in this menu manipulate modes, variables, and the stack.
  360. X
  361. The @key{FLT}, @key{FIX}, @key{SCI}, and @key{ENG} keys select
  362. floating-point, fixed-point, scientific, or engineering notation.
  363. @key{FIX} prompts for the number of digits to display.  You can
  364. respond using the keyboard or the keypad digit and @key{ENTER} keys.
  365. The other three modes always display full precision.  You can
  366. type a numeric prefix using the keyboard, then click on one of
  367. these keys, to set a different display precision.
  368. X
  369. The @key{GRP} key turns grouping of digits with commas on or off.
  370. @kbd{INV GRP} enables grouping to the right of the decimal point as
  371. well as to the left.
  372. X
  373. The @key{RAD} and @key{DEG} keys switch between radians and degrees
  374. for trigonometric functions.
  375. X
  376. The @key{FRAC} key turns Fraction mode on or off.  This affects
  377. whether commands like @kbd{/} with integer arguments produce
  378. fractional or floating-point results.
  379. X
  380. The @key{POLR} key turns Polar mode on or off, determining whether
  381. polar or rectangular complex numbers are used by default.
  382. X
  383. The @key{SYMB} key turns Symbolic mode on or off, in which
  384. operations that would produce inexact floating-point results
  385. are left unevaluated as algebraic formulas.
  386. X
  387. The @key{PREC} key selects the current precision.  Answer with
  388. the keyboard or with the keypad digit and @key{ENTER} keys.
  389. X
  390. The @key{SWAP} key exchanges the top two stack elements.
  391. The @key{RLL3} key rotates the top three stack elements upwards.
  392. The @key{RLL4} key rotates the top four stack elements upwards.
  393. The @key{OVER} key duplicates the second-to-top stack element.
  394. X
  395. The @key{STO} and @key{RCL} keys are analogous to @kbd{s t} and
  396. @kbd{s r} in regular Calc.  @xref{Store and Recall}.  Click the
  397. @key{STO} or @key{RCL} key, then one of the ten digits.  (Named
  398. variables are not available in Keypad Mode.)  You can also use,
  399. for example, @kbd{STO + 3} to add to register 3.
  400. X
  401. @node Embedded Mode, Programming, Keypad Mode, Top
  402. @chapter Embedded Mode
  403. X
  404. @noindent
  405. Embedded Mode in Calc provides an alternative to copying numbers
  406. and formulas back and forth between editing buffers and the Calc
  407. stack.  In Embedded Mode, your editing buffer becomes temporarily
  408. linked to the stack and this copying is taken care of automatically.
  409. X
  410. @menu
  411. * Basic Embedded Mode::
  412. * More About Embedded Mode::
  413. * Assignments in Embedded Mode::
  414. * Mode Settings in Embedded Mode::
  415. * Customizing Embedded Mode::
  416. @end menu
  417. X
  418. @node Basic Embedded Mode, More About Embedded Mode, Embedded Mode, Embedded Mode
  419. @section Basic Embedded Mode
  420. X
  421. @noindent
  422. @kindex M-# e
  423. @pindex calc-embedded
  424. To enter Embedded mode, position the Emacs point (cursor) on a
  425. formula in any buffer and press @kbd{M-# e} (@code{calc-embedded}).
  426. Note that @kbd{M-# e} is not to be used in the Calc stack buffer
  427. like most Calc commands, but rather in regular editing buffers that
  428. are visiting your own files.
  429. X
  430. Calc normally scans backward and forward in the buffer for the
  431. nearest opening and closing @dfn{formula delimiters}.  The simplest
  432. delimiters are blank lines.  Other delimiters that Embedded Mode
  433. understands are:
  434. X
  435. @enumerate
  436. @item
  437. The @TeX{} math delimiters @samp{$ $} @samp{$$ $$}, @samp{\[ \]}, and @samp{\( \)};
  438. @item
  439. Lines beginning with @samp{\begin} and @samp{\end};
  440. @item
  441. Lines beginning with @samp{@@} (Texinfo delimiters).
  442. @item
  443. Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters);
  444. @item
  445. Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else.
  446. @end enumerate
  447. X
  448. @xref{Customizing Embedded Mode}, to see how to make Calc recognize
  449. your own favorite delimiters.  Delimiters like @samp{$ $} can appear
  450. on their own lines or in-line with the formula.
  451. X
  452. If you give a positive or negative numeric prefix argument, Calc
  453. instead uses the current point as one end of the formula, and moves
  454. forward or backward (respectively) by that many lines to find the
  455. other end.  Explicit delimiters are not necessary in this case.
  456. X
  457. With a prefix argument of zero, Calc uses the current region
  458. (delimited by point and mark) instead of formula delimiters.
  459. X
  460. @kindex M-# w
  461. @pindex calc-embedded-word
  462. With a prefix argument of @kbd{C-u} only, Calc scans for the first
  463. non-numeric character (i.e., the first character that is not a
  464. digit, sign, decimal point, or upper- or lower-case @samp{e})
  465. forward and backward to delimit the formula.  @kbd{M-# w}
  466. (@code{calc-embedded-word}) is equivalent to @kbd{C-u M-# e}.
  467. X
  468. When you enable Embedded mode for a formula, Calc reads the text
  469. between the delimiters and tries to interpret it as a Calc formula.
  470. It's best if the current Calc language mode is correct for the
  471. formula, but Calc can generally identify @TeX{} formulas and
  472. Big-style formulas even if the language mode is wrong.  If Calc
  473. can't make sense of the formula, it beeps and refuses to enter
  474. Embedded mode.  But if the current language is wrong, Calc can
  475. sometimes parse the formula successfully (but incorrectly);
  476. for example, the C expression @samp{atan(a[1])} can be parsed
  477. in Normal language mode, but the @code{atan} won't correspond to
  478. the built-in @code{arctan} function, and the @samp{a[1]} will be
  479. interpreted as @samp{a} times the vector @samp{[1]}!
  480. X
  481. If you press @kbd{M-# e} or @kbd{M-# w} to activate an embedded
  482. formula which is blank, say with the cursor on the space between
  483. the two delimiters @samp{$ $}, Calc will immediately prompt for
  484. an algebraic entry.
  485. X
  486. Only one formula in one buffer can be enabled at a time.  If you
  487. move to another area of the current buffer and give Calc commands,
  488. Calc turns Embedded mode off for the old formula and then tries
  489. to restart Embedded mode at the new position.  Other buffers are
  490. not affected by Embedded mode.
  491. X
  492. When Embedded mode begins, Calc pushes the current formula onto
  493. the stack.  No Calc stack window is created; however, Calc copies
  494. the top-of-stack position into the original buffer at all times.
  495. You can create a Calc window by hand with @kbd{M-# o} if you
  496. find you need to see the entire stack.
  497. X
  498. For example, typing @kbd{M-# e} while somewhere in the formula
  499. @samp{n>2} in the following line enables Embedded mode on that
  500. inequality:
  501. X
  502. @example
  503. We define $F_n = F_(n-1)+F_(n-2)$ for all $n>2$.
  504. @end example
  505. X
  506. The formula @cite{n>2} will be pushed onto the Calc stack, and
  507. the top of stack will be copied back into the editing buffer.
  508. This means that spaces will appear around the @samp{>} symbol
  509. to match Calc's usual display style:
  510. X
  511. @example
  512. We define $F_n = F_(n-1)+F_(n-2)$ for all $n > 2$.
  513. @end example
  514. X
  515. No spaces have appeared around the @samp{+} sign because it's
  516. in a different formula, one which we have not yet touched with
  517. Embedded mode.
  518. X
  519. Now that Embedded mode is enabled, keys you type in this buffer
  520. are interpreted as Calc commands.  At this point we might use
  521. the ``commute'' command @kbd{j C} to reverse the inequality.
  522. This is a selection-based command for which we first need to
  523. move the cursor onto the operator (@samp{>} in this case) that
  524. needs to be commuted.
  525. X
  526. @example
  527. We define $F_n = F_(n-1)+F_(n-2)$ for all $2 < n$.
  528. @end example
  529. X
  530. The @kbd{M-# o} command is a useful way to open a Calc window
  531. without actually selecting that window.  Giving this command
  532. verifies that @samp{2 < n} is also on the Calc stack.  Typing
  533. @kbd{17 RET} would produce:
  534. X
  535. @example
  536. We define $F_n = F_(n-1)+F_(n-2)$ for all $17$.
  537. @end example
  538. X
  539. @noindent
  540. with @samp{2 < n} and @samp{17} on the stack; typing @key{TAB}
  541. at this point will exchange the two stack values and restore
  542. @samp{2 < n} to the embedded formula.  Even though you can't
  543. normally see the stack in Embedded mode, it is still there and
  544. it still operates in the same way.  But, as with old-fashioned
  545. RPN calculators, you can only see the value at the top of the
  546. stack at any given time (unless you use @kbd{M-# o}).
  547. X
  548. Typing @kbd{M-# e} again turns Embedded mode off.  The Calc
  549. window reveals that the formula @samp{2 < n} is automatically
  550. removed from the stack, but the @samp{17} is not.  Entering
  551. Embedded mode always pushes one thing onto the stack, and
  552. leaving Embedded mode always removes one thing.  Anything else
  553. that happens on the stack is entirely your business as far as
  554. Embedded mode is concerned.
  555. X
  556. If you press @kbd{M-# e} in the wrong place by accident, it is
  557. possible that Calc will be able to parse the nearby text as a
  558. formula and will mangle that text in an attempt to redisplay it
  559. ``properly'' in the current language mode.  If this happens,
  560. press @kbd{M-# e} again to exit Embedded mode, then give the
  561. regular Emacs ``undo'' command (@kbd{C-_} or @kbd{C-x u}) to put
  562. the text back the way it was before Calc edited it.  Note that Calc's
  563. own Undo command (typed before you turn Embedded mode back off)
  564. will not do you any good, because as far as Calc is concerned
  565. you haven't done anything with this formula yet.
  566. X
  567. @node More About Embedded Mode, Assignments in Embedded Mode, Basic Embedded Mode, Embedded Mode
  568. @section More About Embedded Mode
  569. X
  570. @noindent
  571. When Embedded mode ``activates'' a formula, i.e., when it examines
  572. the formula for the first time since the buffer was created or
  573. loaded, Calc tries to sense the language in which the formula was
  574. written.  If the formula contains any @TeX{}-like @samp{\} sequences,
  575. it is parsed (i.e., read) in @TeX{} mode.  If the formula appears to
  576. be written in multi-line Big mode, it is parsed in Big mode.  Otherwise,
  577. it is parsed according to the current language mode.
  578. X
  579. Note that Calc does not change the current language mode according
  580. to what it finds.  Even though it can read a @TeX{} formula when
  581. not in @TeX{} mode, it will immediately rewrite this formula using
  582. whatever language mode is in effect.  You must then type @kbd{d T}
  583. to switch Calc permanently into @TeX{} mode if that is what you
  584. desire.
  585. X
  586. @tex
  587. \bigskip
  588. @end tex
  589. X
  590. @kindex d p
  591. @pindex calc-show-plain
  592. Calc's parser is unable to read certain kinds of formulas.  For
  593. example, with @kbd{v ]} (@code{calc-matrix-brackets}) you can
  594. specify matrix display styles which the parser is unable to
  595. recognize as matrices.  The @kbd{d p} (@code{calc-show-plain})
  596. command turns on a mode in which a ``plain'' version of a
  597. formula is placed in front of the fully-formatted version.
  598. When Calc reads a formula that has such a plain version in
  599. front, it reads the plain version and ignores the formatted
  600. version.
  601. X
  602. Plain formulas are preceded and followed by @samp{%%%} signs
  603. by default.  This notation has the advantage that the @samp{%}
  604. character begins a comment in @TeX{}, so if your formula is
  605. embedded in a @TeX{} document its plain version will be
  606. invisible in the final printed copy.  @xref{Customizing
  607. Embedded Mode}, to see how to change the ``plain'' formula
  608. delimiters, say to something that @dfn{eqn} or some other
  609. formatter will treat as a comment.
  610. X
  611. There are several notations which Calc's parser for ``big''
  612. formatted formulas can't yet recognize.  In particular, it can't
  613. read the large symbols for @code{sum}, @code{prod}, and @code{integ},
  614. and it can't handle @samp{=>} with the righthand argument omitted.
  615. Also, Calc won't recognize special formats you have defined with
  616. the @kbd{Z C} command (@pxref{User-Defined Compositions}).  In
  617. these cases it is important to use ``plain'' mode to make sure
  618. Calc will be able to read your formula later.
  619. X
  620. Another example where ``plain'' mode is important is if you have
  621. specified a float mode with few digits of precision.  Normally
  622. any digits that are computed but not displayed will simply be
  623. lost when you save and re-load your embedded buffer, but ``plain''
  624. mode allows you to make sure that the complete number is present
  625. in the file as well as the rounded-down number.
  626. X
  627. @tex
  628. \bigskip
  629. @end tex
  630. X
  631. Embedded buffers remember active formulas for as long as they
  632. exist in Emacs memory.  Suppose you have an embedded formula
  633. which is @c{$\pi$}
  634. @cite{pi} to the normal 12 decimal places, and then
  635. type @kbd{C-u 5 d n} to display only five decimal places.
  636. If you then type @kbd{d n}, all 12 places reappear because the
  637. full number is still there on the Calc stack.  More surprisingly,
  638. even if you exit Embedded mode and later re-enter it for that
  639. formula, typing @kbd{d n} will restore all 12 places because
  640. each buffer remembers all its active formulas.  However, if you
  641. save the buffer in a file and reload it in a new Emacs session,
  642. all non-displayed digits will have been lost unless you used
  643. ``plain'' mode.
  644. X
  645. @tex
  646. \bigskip
  647. @end tex
  648. X
  649. In some applications of Embedded mode, you will want to have a
  650. sequence of copies of a formula that show its evolution as you
  651. work on it.  For example, you might want to have a sequence
  652. like this in your file (elaborating here on the example from
  653. the ``Getting Started'' chapter):
  654. X
  655. @smallexample
  656. The derivative of
  657. X
  658. X                              ln(ln(x))
  659. X
  660. is
  661. X
  662. X                  @r{(the derivative of }ln(ln(x))@r{)}
  663. X
  664. whose value at x = 2 is
  665. X
  666. X                            @r{(the value)}
  667. X
  668. and at x = 3 is
  669. X
  670. X                            @r{(the value)}
  671. @end smallexample
  672. X
  673. @kindex M-# d
  674. @pindex calc-embedded-duplicate
  675. The @kbd{M-# d} (@code{calc-embedded-duplicate}) command is a
  676. handy way to make sequences like this.  If you type @kbd{M-# d},
  677. the formula under the cursor (which may or may not have Embedded
  678. mode enabled for it at the time) is copied immediately below and
  679. Embedded mode is then enabled for that copy.
  680. X
  681. For this example, you would start with just
  682. X
  683. @smallexample
  684. The derivative of
  685. X
  686. X                              ln(ln(x))
  687. @end smallexample
  688. X
  689. @noindent
  690. and press @kbd{M-# d} with the cursor on this formula.  The result
  691. is
  692. X
  693. @smallexample
  694. The derivative of
  695. X
  696. X                              ln(ln(x))
  697. X
  698. X
  699. X                              ln(ln(x))
  700. @end smallexample
  701. X
  702. @noindent
  703. with the second copy of the formula enabled in Embedded mode.
  704. You can now press @kbd{a d x RET} to take the derivative, and
  705. @kbd{M-# d M-# d} to make two more copies of the derivative.
  706. To complete the computations, type @kbd{3 s l x RET} to evaluate
  707. the last formula, then move up to the second-to-last formula
  708. and type @kbd{2 s l x RET}.
  709. X
  710. Finally, you would want to press @kbd{M-# e} to exit Embedded
  711. mode, then go up and insert the necessary text in between the
  712. various formulas and numbers.
  713. X
  714. @tex
  715. \bigskip
  716. @end tex
  717. X
  718. @kindex M-# f
  719. @kindex M-# '
  720. @pindex calc-embedded-new-formula
  721. The @kbd{M-# f} (@code{calc-embedded-new-formula}) command
  722. creates a new embedded formula at the current point.  It inserts
  723. some default delimiters, which are usually just blank lines,
  724. and then does an algebraic entry to get the formula (which is
  725. then enabled for Embedded mode).  This is just shorthand for
  726. typing the delimiters yourself, positioning the cursor between
  727. the new delimiters, and pressing @kbd{M-# e}.  The key sequence
  728. @kbd{M-# '} is equivalent to @kbd{M-# f}.
  729. X
  730. @kindex M-# n
  731. @kindex M-# p
  732. @pindex calc-embedded-next
  733. @pindex calc-embedded-previous
  734. The @kbd{M-# n} (@code{calc-embedded-next}) and @kbd{M-# p}
  735. (@code{calc-embedded-previous}) commands move the cursor to the
  736. next or previous active embedded formula in the buffer.  They
  737. can take positive or negative prefix arguments to move by several
  738. formulas.  Note that these commands do not actually examine the
  739. text of the buffer looking for formulas; they only see formulas
  740. which have previously been activated in Embedded mode.  In fact,
  741. @kbd{M-# n} and @kbd{M-# p} are a useful way to tell which
  742. embedded formulas are currently active.  Also, note that these
  743. commands do not enable Embedded mode on the next or previous
  744. formula, they just move the cursor.  (By the way, @kbd{M-# n} is
  745. not as awkward to type as it may seem, because @kbd{M-#} ignores
  746. Shift and Meta on the second keystroke:  @kbd{M-# M-N} can be typed
  747. by holding down Shift and Meta and alternately typing two keys.)
  748. X
  749. @kindex M-# `
  750. @pindex calc-embedded-edit
  751. The @kbd{M-# `} (@code{calc-embedded-edit}) command edits the
  752. embedded formula at the current point as if by @kbd{`} (@code{calc-edit}).
  753. Embedded mode does not have to be enabled for this to work.  Press
  754. @kbd{M-# M-#} to finish the edit, or @kbd{M-# x} to cancel.
  755. X
  756. @node Assignments in Embedded Mode, Mode Settings in Embedded Mode, More About Embedded Mode, Embedded Mode
  757. @section Assignments in Embedded Mode
  758. X
  759. @noindent
  760. The @samp{:=} (assignment) and @samp{=>} (``evaluates-to'') operators
  761. are especially useful in Embedded mode.  They allow you to make
  762. a definition in one formula, then refer to that definition in
  763. other formulas embedded in the same buffer.
  764. X
  765. An embedded formula which is an assignment to a variable, as in
  766. X
  767. @example
  768. foo := 5
  769. @end example
  770. X
  771. @noindent
  772. records @cite{5} as the stored value of @code{foo} for the
  773. purposes of Embedded mode operations in the current buffer.  It
  774. does @emph{not} actually store @cite{5} as the ``global'' value
  775. of @code{foo}, however.  Regular Calc operations, and Embedded
  776. formulas in other buffers, will not see this assignment.
  777. X
  778. One way to use this assigned value is simply to create an
  779. Embedded formula elsewhere that refers to @code{foo}, and to press
  780. @kbd{=} in that formula.  However, this permanently replaces the
  781. @code{foo} in the formula with its current value.  More interesting
  782. is to use @samp{=>} elsewhere:
  783. X
  784. @example
  785. foo + 7 => 12
  786. @end example
  787. X
  788. @xref{Evaluates-To Operator}, for a general discussion of @samp{=>}.
  789. X
  790. If you move back and change the assignment to @code{foo}, any
  791. @samp{=>} formulas which refer to it are automatically updated.
  792. X
  793. @example
  794. foo := 17
  795. X
  796. foo + 7 => 24
  797. @end example
  798. X
  799. The obvious question then is, @emph{how} can one easily change the
  800. assignment to @code{foo}?  If you simply select the formula in
  801. Embedded mode and type 17, the assignment itself will be replaced
  802. by the 17.  The effect on the other formula will be that the
  803. variable @code{foo} becomes unassigned:
  804. X
  805. @example
  806. 17
  807. X
  808. foo + 7 => foo + 7
  809. @end example
  810. X
  811. The right thing to do is first to use a selection command (@kbd{j 2}
  812. will do the trick) to select the righthand side of the assignment.
  813. Then, @kbd{17 TAB DEL} will swap the 17 into place (@pxref{Selecting
  814. Subformulas}, to see how this works).
  815. X
  816. @kindex M-# j
  817. @pindex calc-embedded-select
  818. The @kbd{M-# j} (@code{calc-embedded-select}) command provides an
  819. easy way to operate on assigments.  It is just like @kbd{M-# e},
  820. except that if the enabled formula is an assignment, it uses
  821. @kbd{j 2} to select the righthand side.  If the enabled formula
  822. is an evaluates-to, it uses @kbd{j 1} to select the lefthand side.
  823. A formula can also be a combination of both:
  824. X
  825. @example
  826. bar := foo + 3 => 20
  827. @end example
  828. X
  829. @noindent
  830. in which case @kbd{M-# j} will select the middle part (@samp{foo + 3}).
  831. X
  832. The formula is automatically deselected when you leave Embedded
  833. mode.
  834. X
  835. @kindex M-# u
  836. @kindex M-# =
  837. @pindex calc-embedded-update
  838. Another way to change the assignment to @code{foo} would simply be
  839. to edit the number using regular Emacs editing rather then Embedded
  840. mode.  Then, we have to find a way to get Embedded mode to notice
  841. the change.  The @kbd{M-# u} or @kbd{M-# =}
  842. (@code{calc-embedded-update-formula}) command is a convenient way
  843. to do this.@refill
  844. X
  845. @example
  846. foo := 6
  847. X
  848. foo + 7 => 13
  849. @end example
  850. X
  851. Pressing @kbd{M-# u} is much like pressing @kbd{M-# e = M-# e}, that
  852. is, temporarily enabling Embedded mode for the formula under the
  853. cursor and then evaluating it with @kbd{=}.  But @kbd{M-# u} does
  854. not actually use @kbd{M-# e}, and in fact another formula somewhere
  855. else can be enabled in Embedded mode while you use @kbd{M-# u} and
  856. that formula will not be disturbed.
  857. X
  858. With a numeric prefix argument, @kbd{M-# u} updates all active
  859. @samp{=>} formulas in the buffer.  Formulas which have not yet
  860. been activated in Embedded mode, and formulas which do not have
  861. @samp{=>} as their top-level operator, are not affected by this.
  862. X
  863. With a plain @kbd{C-u} prefix, @kbd{C-u M-# u} updates only in the
  864. region between mark and point rather than in the whole buffer.
  865. X
  866. @kbd{M-# u} is also a handy way to activate a formula, such as an
  867. @samp{=>} formula that has freshly been typed in or loaded from a
  868. file.
  869. X
  870. @kindex M-# a
  871. @pindex calc-embedded-activate
  872. The @kbd{M-# a} (@code{calc-embedded-activate}) command scans
  873. through the current buffer and activates all embedded formulas
  874. that contain @samp{:=} or @samp{=>} symbols.  This does not mean
  875. that Embedded mode is actually turned on, but only that the
  876. formulas' positions are registered with Embedded mode so that
  877. the @samp{=>} values can be properly updated as assignments are
  878. changed.
  879. X
  880. It is a good idea to type @kbd{M-# a} right after loading a file
  881. that uses embedded @samp{=>} operators.  Emacs includes a nifty
  882. ``buffer-local variables'' feature that you can use to do this
  883. automatically.  The idea is to place near the end of your file
  884. a few lines that look like this:
  885. X
  886. @example
  887. --- Local Variables: ---
  888. --- eval:(calc-embedded-activate) ---
  889. --- End: ---
  890. @end example
  891. X
  892. @noindent
  893. where the leading and trailing @samp{---} can be replaced by
  894. any suitable strings (which must be the same on all three lines)
  895. or omitted altogether; in a @TeX{} file, @samp{%} would be a good
  896. leading string and no trailing string would be necessary.  In a
  897. C program, @samp{/*} and @samp{*/} would be good leading and
  898. trailing strings.
  899. X
  900. When Emacs loads a file into memory, it checks for a Local Variables
  901. section like this one at the end of the file.  If it finds this
  902. section, it does the specified things (in this case, running
  903. @kbd{M-# a} automatically) before editing of the file begins.
  904. The Local Variables section must be within 3000 characters of the
  905. end of the file for Emacs to find it, and it must be in the last
  906. page of the file if the file has any page separators.
  907. @xref{File Variables, , Local Variables in Files, emacs, the
  908. Emacs manual}.
  909. X
  910. Note that @kbd{M-# a} does not update the formulas it finds.
  911. To do this, type, say, @kbd{M-1 M-# u} after @kbd{M-# a}.
  912. Generally this should not be a problem, though, because the
  913. formulas will have been up-to-date already when the file was
  914. saved.
  915. X
  916. Normally, @kbd{M-# a} activates all the formulas it finds, but
  917. any previous active formulas remain active as well.  With a
  918. positive numeric prefix argument, @kbd{M-# a} first deactivates
  919. all current active formulas, then actives the ones it finds in
  920. its scan of the buffer.  With a negative prefix argument,
  921. @kbd{M-# a} simply deactivates all formulas.
  922. X
  923. Embedded mode has two symbols, @samp{Active} and @samp{~Active},
  924. which it puts next to the major mode name in a buffer's mode line.
  925. It puts @samp{Active} if it has reason to believe that all
  926. formulas in the buffer are active, because you have typed @kbd{M-# a}
  927. and Calc has not since had to deactivate any formulas (which can
  928. happen if Calc goes to update an @samp{=>} formula somewhere because
  929. a variable changed, and finds that the formula is no longer there
  930. due to some kind of editing outside of Embedded mode).  Calc puts
  931. @samp{~Active} in the mode line if some, but probably not all,
  932. formulas in the buffer are active.  This happens if you activate
  933. a few formulas one at a time but never use @kbd{M-# a}, or if you
  934. used @kbd{M-# a} but then Calc had to deactivate a formula
  935. because it lost track of it.  If neither of these symbols appears
  936. in the mode line, no embedded formulas are active in the buffer
  937. (e.g., before Embedded mode has been used, or after a @kbd{M-- M-# a}).
  938. X
  939. Embedded formulas can refer to assignments both before and after them
  940. in the buffer.  If there are several assignments to a variable, the
  941. nearest preceding assignment is used if there is one, otherwise the
  942. following assignment is used.
  943. X
  944. @example
  945. x => 1
  946. X
  947. x := 1
  948. X
  949. x => 1
  950. X
  951. x := 2
  952. X
  953. x => 2
  954. @end example
  955. X
  956. As well as simple variables, you can also assign to subscript
  957. expressions of the form @samp{@var{var}_@var{number}} (as in
  958. @code{x_0}), or @samp{@var{var}_@var{var}} (as in @code{x_max}).
  959. Assignments to other kinds of objects can be represented by Calc,
  960. but the automatic linkage between assignments and references works
  961. only for plain variables and these two kinds of subscript expressions.
  962. X
  963. If there are no assignments to a given variable, the global
  964. stored value for the variable is used (@pxref{Storing Variables}),
  965. or, if no value is stored, the variable is left in symbolic form.
  966. Note that global stored values will be lost when the file is saved
  967. and loaded in a later Emacs session, unless you have used the
  968. @kbd{s p} (@code{calc-permanent-variable}) command to save them;
  969. @pxref{Operations on Variables}.
  970. X
  971. The @kbd{m C} (@code{calc-auto-recompute}) command turns automatic
  972. recomputation of @samp{=>} forms on and off.  If you turn automatic
  973. recomputation off, you will have to use @kbd{M-# u} to update these
  974. formulas manually after an assignment has been changed.  If you
  975. plan to change several assignments at once, it may be more efficient
  976. to type @kbd{m C}, change all the assignments, then use @kbd{M-1 M-# u}
  977. to update the entire buffer afterwards.  The @kbd{m C} command also
  978. controls @samp{=>} formulas on the stack; @pxref{Evaluates-To
  979. Operator}.  When you turn automatic recomputation back on, the
  980. stack will be updated but the Embedded buffer will not; you must
  981. use @kbd{M-# u} to update the buffer by hand.
  982. X
  983. @node Mode Settings in Embedded Mode, Customizing Embedded Mode, Assignments in Embedded Mode, Embedded Mode
  984. @section Mode Settings in Embedded Mode
  985. X
  986. @noindent
  987. Embedded Mode has a rather complicated mechanism for handling mode
  988. settings in Embedded formulas.  It is possible to put annotations
  989. in the file that specify mode settings either global to the entire
  990. file or local to a particular formula or formulas.  In the latter
  991. case, different modes can be specified for use when a formula
  992. is the enabled Embedded Mode formula.
  993. X
  994. When you give any mode-setting command, like @kbd{m f} (for fraction
  995. mode) or @kbd{d s} (for scientific notation), Embedded Mode adds
  996. a line like the following one to the file just before the opening
  997. delimiter of the formula.
  998. X
  999. @example
  1000. % [calc-mode: fractions: t]
  1001. % [calc-mode: float-format: (sci 0)]
  1002. @end example
  1003. X
  1004. When Calc interprets an embedded formula, it scans the text before
  1005. the formula for mode-setting annotations like these and sets the
  1006. Calc buffer to match these modes.  Modes not explicitly described
  1007. in the file are not changed.  Calc scans all the way to the top of
  1008. the file, or until a line of the form
  1009. X
  1010. @example
  1011. % [calc-defaults]
  1012. @end example
  1013. X
  1014. @noindent
  1015. which you can insert at strategic places in the file if this backward
  1016. scan is getting too slow, or just to provide a barrier between one
  1017. ``zone'' of mode settings and another.
  1018. X
  1019. If the file contains several annotations for the same mode, the
  1020. closest one before the formula is used.  Annotations after the
  1021. formula are never used (except for global annotations, described
  1022. below).
  1023. X
  1024. The scan does not look for the leading @samp{% }, only for the
  1025. square brackets and the text they enclose.  You can edit the mode
  1026. annotations to a style that works better in context if you wish.
  1027. @xref{Customizing Embedded Mode}, to see how to change the style
  1028. that Calc uses when it generates the annotations.  You can write
  1029. mode annotations into the file yourself if you know the syntax;
  1030. the easiest way to find the syntax for a given mode is to let
  1031. Calc write the annotation for it once and see what it does.
  1032. X
  1033. If you give a mode-changing command for a mode that already has
  1034. a suitable annotation just above the current formula, Calc will
  1035. modify that annotation rather than generating a new, conflicting
  1036. one.
  1037. X
  1038. Mode annotations have three parts, separated by colons.  (Spaces
  1039. after the colons are optional.)  The first identifies the kind
  1040. of mode setting, the second is a name for the mode itself, and
  1041. the third is the value in the form of a Lisp symbol, number,
  1042. or list.  Annotations with unrecognizable text in the first or
  1043. second parts are ignored.  The third part is not checked to make
  1044. sure the value is of a legal type or range; if you write an
  1045. annotation by hand, be sure to give a proper value or results
  1046. will be unpredictable.  Mode setting annotations are case-sensitive.
  1047. X
  1048. While Embedded Mode is enabled, the word @code{Local} appears in
  1049. the mode line.  This is to show that mode setting commands generate
  1050. annotations that are ``local'' to the current formula or set of
  1051. formulas.  The @kbd{m R} (@code{calc-mode-record-mode}) command
  1052. causes Calc to generate different kinds of annotations.  Pressing
  1053. @kbd{m R} repeatedly cycles through the possible modes.
  1054. X
  1055. @code{LocEdit} and @code{LocPerm} modes generate annotations
  1056. that look like this, respectively:
  1057. X
  1058. @example
  1059. % [calc-edit-mode: fractions t]
  1060. % [calc-perm-mode: fractions nil]
  1061. @end example
  1062. X
  1063. The first kind of annotation will be used only while a formula
  1064. is enabled in Embedded Mode.  The second kind will be used only
  1065. when the formula is @emph{not} enabled.  (Whether the formula
  1066. is ``active'' or not, i.e., whether Calc has seen this formula
  1067. yet, is not relevant here.)
  1068. X
  1069. @code{Global} mode generates an annotation like this at the end
  1070. of the file:
  1071. X
  1072. @example
  1073. % [calc-global-mode: fractions t]
  1074. @end example
  1075. X
  1076. Global mode annotations affect all formulas throughout the file,
  1077. and may appear anywhere in the file.  This allows you to tuck your
  1078. mode annotations somewhere out of the way, say, on a new page of
  1079. the file, as long as those mode settings are suitable for all
  1080. formulas in the file.
  1081. X
  1082. Enabling a formula with @kbd{M-# e} causes a fresh scan for local
  1083. mode annotations; you will have to use this after adding annotations
  1084. above a formula by hand to get the formula to notice them.  Updating
  1085. a formula with @kbd{M-# u} will also re-scan the local modes, but
  1086. global modes are only re-scanned by @kbd{M-# a}
  1087. (@code{calc-embedded-activate}).
  1088. X
  1089. Another way that modes can get out of date is if you add a local
  1090. mode annotation to a formula that has another formula after it.
  1091. In this example, we have used the @kbd{d s} command while the
  1092. first of the two embedded formulas is active.  But the second
  1093. formula has not changed its style to match, even though by the
  1094. rules of reading annotations the @samp{(sci 0)} applies to it, too.
  1095. X
  1096. @example
  1097. % [calc-mode: float-format: (sci 0)]
  1098. 1.23e2
  1099. X
  1100. 456.
  1101. @end example
  1102. X
  1103. We would have to go down to the other formula and press @kbd{M-# u}
  1104. on it in order to get it to notice the new annotation.
  1105. X
  1106. Two more mode-recording mode selectable by @kbd{m R} are @code{Save}
  1107. (which works even outside of Embedded Mode), in which mode settings
  1108. are recorded permanently in your Emacs startup file @file{~/.emacs}
  1109. rather than by annotating the current document, and no-recording
  1110. mode (where there is no symbol like @code{Save} or @code{Local} in
  1111. the mode line), in which mode-changing commands do not leave any
  1112. annotations at all.
  1113. X
  1114. When Embedded Mode is not enabled, mode-recording modes except
  1115. for @code{Save} have no effect.
  1116. X
  1117. @node Customizing Embedded Mode, , Mode Settings in Embedded Mode, Embedded Mode
  1118. @section Customizing Embedded Mode
  1119. X
  1120. @noindent
  1121. You can modify Embedded Mode's behavior by setting various Lisp
  1122. variables described here.  Use @kbd{M-x set-variable} or
  1123. @kbd{M-x edit-options} to adjust a variable on the fly, or
  1124. put a suitable @code{setq} statement in your @file{~/.emacs}
  1125. file to set a variable permanently.  (Another possibility would
  1126. be to use a file-local variable annotation at the end of the
  1127. file; @xref{File Variables, , Local Variables in Files, emacs, the
  1128. Emacs manual}.)
  1129. X
  1130. While none of these variables will be buffer-local by default, you
  1131. can make any of them local to any embedded-mode buffer.  (Their
  1132. values in the @samp{*Calculator*} buffer are never used.)
  1133. X
  1134. @vindex calc-embedded-open-formula
  1135. The @code{calc-embedded-open-formula} variable holds a regular
  1136. expression for the opening delimiter of a formula.  @xref{Regexp Search,
  1137. , Regular Expression Search, emacs, the Emacs manual}, to see
  1138. how regular expressions work.  Basically, a regular expression is a
  1139. pattern that Calc can search for.  A regular expression that considers
  1140. blank lines, @samp{$}, and @samp{$$} to be opening delimiters is
  1141. @code{"\\`\\|^\n\\|\\$\\$?"}.  Just in case the meaning of this
  1142. regular expression is not completely plain, let's go through it
  1143. in detail.
  1144. X
  1145. The surrounding @samp{" "} marks quote the text between them as a
  1146. Lisp string.  If you left them off, @code{set-variable} or
  1147. @code{edit-options} would try to read the regular expression as a
  1148. Lisp program.
  1149. X
  1150. The most obvious property of this regular expression is that it
  1151. contains indecently many backslashes.  There are actually two levels
  1152. of backslash usage going on here.  First, when Lisp reads a quoted
  1153. string, all pairs of characters beginning with a backslash are
  1154. interpreted as special characters.  Here, @code{\n} changes to a
  1155. new-line character, and @code{\\} changes to a single backslash.
  1156. So the actual regular expression seen by Calc is
  1157. @samp{\`\|^ @r{(newline)} \|\$\$?}.
  1158. X
  1159. Regular expressions also consider pairs beginning with backslash
  1160. to have special meanings.  Sometimes the backslash is used to quote
  1161. a character that otherwise would have a special meaning in a regular
  1162. expression, like @samp{$}, which normally means ``end-of-line,''
  1163. or @samp{?}, which means that the preceding item is optional.  So
  1164. @samp{\$\$?} matches either one or two dollar signs.
  1165. X
  1166. The other codes in this regular expression are @samp{^}, which matches
  1167. ``beginning-of-line,'' @samp{\|}, which means ``or,'' and @samp{\`},
  1168. which matches ``beginning-of-buffer.''  So the whole pattern means
  1169. that a formula begins at the beginning of the buffer, or on a newline
  1170. that occurs at the beginning of a line (i.e., a blank line), or at
  1171. one or two dollar signs.
  1172. X
  1173. The default value of @code{calc-embedded-open-formula} looks just
  1174. like this example, with several more alternatives added on to
  1175. recognize various other common kinds of delimiters.
  1176. X
  1177. By the way, the reason to use @samp{^\n} rather than @samp{^$}
  1178. or @samp{\n\n}, which also would appear to match blank lines,
  1179. is that the former expression actually ``consumes'' only one
  1180. newline character as @emph{part of} the delimiter, whereas the
  1181. latter expressions consume zero or two newlines, respectively.
  1182. The former choice gives the most natural behavior when Calc
  1183. must operate on a whole formula including its delimiters.
  1184. X
  1185. See the Emacs manual for complete details on regular expressions.
  1186. But just for your convenience, here is a list of all characters
  1187. which must be quoted with backslash (like @samp{\$}) to avoid
  1188. some special interpretation:  @samp{. * + ? [ ] ^ $ \}.  (Note
  1189. the backslash in this list; for example, to match @samp{\[} you
  1190. must use @samp{"\\\\\\["}.  An exercise for the reader is to
  1191. account for each of these six backslashes!)
  1192. X
  1193. @vindex calc-embedded-close-formula
  1194. The @code{calc-embedded-close-formula} variable holds a regular
  1195. expression for the closing delimiter of a formula.  A closing
  1196. regular expression to match the above example would be
  1197. @samp{"\\'\\|\n$\\|\\$\\$?"}.  This is almost the same as the
  1198. other one, except it now uses @samp{\'} (``end-of-buffer'') and
  1199. @samp{\n$} (newline occurring at end of line, yet another way
  1200. of describing a blank line that is more appropriate for this
  1201. case).
  1202. X
  1203. @vindex calc-embedded-open-word
  1204. @vindex calc-embedded-close-word
  1205. The @code{calc-embedded-open-word} and @code{calc-embedded-close-word}
  1206. variables are similar expressions used when you type @kbd{M-# w}
  1207. instead of @kbd{M-# e} to enable Embedded mode.
  1208. X
  1209. @vindex calc-embedded-open-plain
  1210. The @code{calc-embedded-open-plain} variable is a string which
  1211. begins a ``plain'' formula written in front of the formatted
  1212. formula when @kbd{d p} mode is turned on.  Note that this is an
  1213. actual string, not a regular expression, because Calc must be able
  1214. to write this string into a buffer as well as to recognize it.
  1215. The default string is @samp{"%%% "} (note the trailing space).
  1216. X
  1217. @vindex calc-embedded-close-plain
  1218. The @code{calc-embedded-close-plain} variable is a string which
  1219. ends a ``plain'' formula.  The default is @samp{" %%%\n"}.  Without
  1220. the trailing newline here, the first line of a ``big'' mode formula
  1221. that followed might be shifted over with respect to the other lines.
  1222. X
  1223. @vindex calc-embedded-open-new-formula
  1224. The @code{calc-embedded-open-new-formula} variable is a string
  1225. which is inserted at the front of a new formula when you type
  1226. @kbd{M-# f}.  Its default value is @samp{"\n\n"}.  If this
  1227. string begins with a newline character and the @kbd{M-# f} is
  1228. typed at the beginning of a line, @kbd{M-# f} will skip this
  1229. first newline to avoid introducing unnecessary blank lines in
  1230. the file.
  1231. X
  1232. @vindex calc-embedded-close-new-formula
  1233. The @code{calc-embedded-close-new-formula} variable is the corresponding
  1234. string which is inserted at the end of a new formula.  Its default
  1235. value is also @samp{"\n\n"}.  The final newline is omitted by
  1236. @kbd{M-# f} if typed at the end of a line.  (It follows that if
  1237. @kbd{M-# f} is typed on a blank line, both a leading opening
  1238. newline and a trailing closing newline are omitted.)
  1239. X
  1240. @vindex calc-embedded-announce-formula
  1241. The @code{calc-embedded-announce-formula} variable is a regular
  1242. expression which is sure to be followed by an embedded formula.
  1243. The @kbd{M-# a} command searches for this pattern as well as for
  1244. @samp{=>} and @samp{:=} operators.  Note that @kbd{M-# a} will
  1245. not activate just anything surrounded by formula delimiters; after
  1246. all, blank lines are considered formula delimiters by default!
  1247. But if your language includes a delimiter which can only occur
  1248. actually in front of a formula, you can take advantage of it here.
  1249. The default pattern is @samp{"%Embed\n\\(% .*\n\\)*"}, which
  1250. checks for @samp{%Embed} followed by any number of lines beginning
  1251. with @samp{%} and a space.  This last is important to make Calc
  1252. consider mode annotations part of the pattern, so that the formula's
  1253. opening delimiter really is sure to follow the pattern.
  1254. X
  1255. @vindex calc-embedded-open-mode
  1256. The @code{calc-embedded-open-mode} variable is a string (not a
  1257. regular expression) which should precede a mode annotation.
  1258. Calc never scans for this string; Calc always looks for the
  1259. annotation itself.  But this is the string that is inserted before
  1260. the opening bracket when Calc adds an annotation on its own.
  1261. The default is @samp{"% "}.
  1262. X
  1263. @vindex calc-embedded-close-mode
  1264. The @code{calc-embedded-close-mode} variable is a string which
  1265. follows a mode annotation written by Calc.  Its default value
  1266. is simply a newline, @samp{"\n"}.  If you change this, it is a
  1267. good idea still to end with a newline so that mode annotations
  1268. will appear on lines by themselves.
  1269. X
  1270. @node Programming, Installation, Embedded Mode, Top
  1271. @chapter Programming
  1272. X
  1273. @noindent
  1274. There are several ways to ``program'' the Emacs Calculator, depending
  1275. on the nature of the problem you need to solve.
  1276. X
  1277. @enumerate
  1278. @item
  1279. @dfn{Keyboard macros} allow you to record a sequence of keystrokes
  1280. and play them back at a later time.  This is just the standard Emacs
  1281. keyboard macro mechanism, dressed up with a few more features such
  1282. as loops and conditionals.
  1283. X
  1284. @item
  1285. @dfn{Algebraic definitions} allow you to use any formula to define a
  1286. new function.  This function can then be used in algebraic formulas or
  1287. as an interactive command.
  1288. X
  1289. @item
  1290. @dfn{Rewrite rules} are discussed in the section on algebra commands.
  1291. @xref{Rewrite Rules}.  If you put your rewrite rules in the variable
  1292. @code{EvalRules}, they will be applied automatically to all Calc
  1293. results in just the same way as an internal ``rule'' is applied to
  1294. evaluate @samp{sqrt(9)} to 3 and so on.  @xref{Automatic Rewrites}.
  1295. X
  1296. @item
  1297. @dfn{Lisp} is the programming language that Calc (and most of Emacs)
  1298. is written in.  If the above techniques aren't powerful enough, you
  1299. can write Lisp functions to do anything that built-in Calc commands
  1300. can do.  Lisp code is also somewhat faster than keyboard macros or
  1301. rewrite rules.
  1302. @end enumerate
  1303. X
  1304. Programming features are available through the @kbd{z} and @kbd{Z}
  1305. prefix keys.  New commands that you define are two-key sequences
  1306. beginning with @kbd{z}.  Commands for managing these definitions
  1307. use the shift-@kbd{Z} prefix.  (The @kbd{Z T} (@code{calc-timing})
  1308. command is described elsewhere; @pxref{Troubleshooting Commands}.
  1309. The @kbd{Z C} (@code{calc-user-define-composition}) command is also
  1310. described elsewhere; @pxref{User-Defined Compositions}.)
  1311. X
  1312. @menu
  1313. * Creating User Keys::
  1314. * Keyboard Macros::
  1315. * Invocation Macros::
  1316. * Algebraic Definitions::
  1317. * Lisp Definitions::
  1318. @end menu
  1319. X
  1320. @node Creating User Keys, Keyboard Macros, Programming, Programming
  1321. @section Creating User Keys
  1322. X
  1323. @noindent
  1324. @kindex Z D
  1325. @pindex calc-user-define
  1326. Any Calculator command may be bound to a key using the @kbd{Z D}
  1327. (@code{calc-user-define}) command.  Actually, it is bound to a two-key
  1328. sequence beginning with the @kbd{z} prefix.  (Note that the commands
  1329. for programming begin with shift-@kbd{Z}, and your own commands begin
  1330. with unshifted @kbd{z}.)
  1331. X
  1332. The @kbd{Z D} command first prompts for the key to define.  For example,
  1333. press @kbd{Z D a} to define the new key sequence @kbd{z a}.  You are then
  1334. prompted for the name of the Calculator command that this key should
  1335. run.  For example, the @code{calc-sincos} command is not normally
  1336. available on a key.  Typing @kbd{Z D s sincos @key{RET}} programs the
  1337. @kbd{z s} key sequence to run @code{calc-sincos}.  This definition will remain
  1338. in effect for the rest of this Emacs session, or until you redefine
  1339. @kbd{z s} to be something else.
  1340. X
  1341. You can actually bind any Emacs command to a @kbd{z} key sequence by
  1342. backspacing over the @samp{calc-} when you are prompted for the command name.
  1343. X
  1344. As with any other prefix key, you can type @kbd{z ?} to see a list of
  1345. all the two-key sequences you have defined that start with @kbd{z}.
  1346. Initially, no @kbd{z} sequences (except @kbd{z ?} itself) are defined.
  1347. X
  1348. User keys are typically letters, but may in fact use any key.
  1349. (@key{META}-keys are not permitted, nor are a terminal's special
  1350. function keys which generate multi-character sequences when pressed.)
  1351. You can define different commands on the shifted and unshifted versions
  1352. of a letter if you wish.
  1353. X
  1354. @kindex Z U
  1355. @pindex calc-user-undefine
  1356. The @kbd{Z U} (@code{calc-user-undefine}) command unbinds a user key.
  1357. For example, the key sequence @kbd{Z U s} will undefine the @code{sincos}
  1358. key we defined above.
  1359. X
  1360. @kindex Z P
  1361. @pindex calc-user-define-permanent
  1362. @cindex Storing user definitions
  1363. @cindex Permanent user definitions
  1364. @cindex @file{.emacs} file, user-defined commands
  1365. The @kbd{Z P} (@code{calc-user-define-permanent}) command makes a key
  1366. binding permanent so that it will remain in effect even in future Emacs
  1367. sessions.  (It does this by adding a suitable bit of Lisp code into
  1368. your @file{.emacs} file.)  For example, @kbd{Z P s} would register
  1369. our @code{sincos} command permanently.  If you later wish to unregister
  1370. this command you must edit your @file{.emacs} file by hand.
  1371. (@xref{General Mode Commands}, for a way to tell Calc to use a
  1372. different file instead of @file{.emacs}.)
  1373. X
  1374. The @kbd{Z P} command also saves the user definition, if any, for the
  1375. command bound to the key.  After @kbd{Z F} and @kbd{Z C}, a given user
  1376. key could invoke a command, which in turn calls an algebraic function,
  1377. which might have one or more special display formats.  A single @kbd{Z P}
  1378. command will save all of these definitions.
  1379. X
  1380. To save a command or function without its key binding (or if there is
  1381. no key binding for the command or function), type @kbd{'} (the apostrophe)
  1382. when prompted for a key.  Then, type the function name, or backspace
  1383. to change the @samp{calcFunc-} prefix to @samp{calc-} and enter a
  1384. command name.  (If the command you give implies a function, the function
  1385. will be saved, and if the function has any display formats, those will
  1386. be saved, but not the other way around:  Saving a function will not save
  1387. any commands or key bindings associated with the function.)
  1388. SHAR_EOF
  1389. true || echo 'restore of calc.texinfo failed'
  1390. fi
  1391. echo 'End of  part 51'
  1392. echo 'File calc.texinfo is continued in part 52'
  1393. echo 52 > _shar_seq_.tmp
  1394. exit 0
  1395. exit 0 # Just in case...
  1396. -- 
  1397. Kent Landfield                   INTERNET: kent@sparky.IMD.Sterling.COM
  1398. Sterling Software, IMD           UUCP:     uunet!sparky!kent
  1399. Phone:    (402) 291-8300         FAX:      (402) 291-4362
  1400. Please send comp.sources.misc-related mail to kent@uunet.uu.net.
  1401.